This document describes how the Japanese Language Kit works and what it takes for an application to be WorldScript savvy . Developers following these guidelines will have multilingual applications that will be easy to localize, and can be sold worldwide.
The Japanese Language Kit breaks geographic boundaries, so even products intended for exclusive use in the United States should follow the guidelines contained in this document. Developers with multilingual markets will especially find this information to be useful.
The following information explains why the Japanese Language Kit is significant and what you need to do and know to be compatible along with a a list of areas to test. Finally there is a glossary defining italicized terms and a list of references for further information.
What is the Japanese Language Kit?
The Japanese Language Kit contains the system extensions and fonts necessary to support Japanese text on any localized 7.1 System (eg. English, French, Korean). The Japanese Language Kit will be available outside the US and is being tested with most of our localized non-Roman system software. Although Japanese is the only Language Kit announced, the product is designed to support all of our script systems and therefore has the potential for a broad effect on users and applications worldwide.
How does it concern developers?
The Japanese Language Kit introduces a significant change for the international product model. There is now a looser relationship between the language of the user interface and the languages supported by the System and in the application’s documents. This allows more freedom to create global multilingual products.
In the past, the ‘localization’ model entailed that each region had products that were translated and modified to support the local language and culture (eg. Japanese for Japan and French for France). Each product might have unique code to support a local requirement, such as two-byte characters, unusual formatting, or a cultural difference. Sometimes, these differences were so extreme that the localized and original versions of the product could no longer even exchange data files, making it difficult for users.
Now, the model is to ‘globalize’, or have each base product support a range of (if not all) languages, independent of the language used for the human interface. For example, an Arabic version of a word processor which can support Japanese: it should be able to exchange bilingual Arabic/Japanese documents with other localized versions of the same product.
Unlocalized English applications will be effected by the Japanese Language Kit in several ways. Users will expect their products to be compatible with all the fonts in their system, even those added with the Japanese Language Kit. Products that follow the Script Manager guidelines or use TextEdit will have minimal problems and the users will be basically satisfied. But if your application already has serious problems working on a KanjiTalk System, then you can expect complaints from your users with the Japanese Language Kit.
Although most applications are originally developed in the United States, they eventually find their way to markets around the world. While localized products are preferred, unlocalized English applications generate a significant number of sales to users in every international market.
In a region like Israel, Japanese Language Kit users will a have tri-script system - Hebrew will be their primary script , and Japanese and Roman will be secondary scripts (the Roman script is included on all systems). Using the Language Register utility, users will be able to correctly set the language for an application’s user interface elements. In fact the user is setting the application script - this affects the system font used vy the application. Developers should be aware of this and decide how they want to handle it.
Most of the business world is multilingual, especially outside of the United States, and English is not the only second language. This is a big opportunity for products to distinguish themselves from their monolingual competition. What may appear to be a niche market, is actually Apple’s fastest growing market with tremendous potential worldwide.
What do developers need to do?
Here is a list of what needs to be done to be WorldScript Savvy. You can find more details below.
• Use TextEdit or the Script Manager for all text processing.
- Watch out for your TextEdit patches.
- Minimize special case code for ASCII text.
- Use AddResMenu() for font menus and beware of custom mdefs.
- Don’t assume that a character is one byte.
- Check for compatibility with English word breaking and line wrapping routines.
- Don’t hard code fonts.
• Be sure that your application’s version resource region code is set properly.
• Set the creator of associate application files to the application signature.
• Check to see if a script is enabled and reference its resources explicitly.
• Store both the font name and FOND ID so that appropriate fonts can be substituted.
• Implement inline two-byte text entry support using the Text Services Manager.
• Applications with multilingual user interface resources should use the preferred language associated with the application script at launch.
• Work around multiscript text limitations in the Toolbox by creating a custom mdef, wdef, and avoiding the Dialog Manager.
Script Manager Compatibility
The main thing that all applications should do to work with the Japanese Language Kit is to be Script Manager compatible. If you have not given the Script Manager a lot of attention yet, now is a good time because the introduction of the Japanese Language Kit make it more relevant and the documentation is complete (see references). Here are some of my favorite tricks and recommendations.
• Painless Implementation: If your application uses mostly TextEdit, then 95% of the work is already done for you because TextEdit is Script Manager compatible, and Styled TextEdit supports multiscript text. Most TextEdit bugs are introduced by the application’s custom hooks and patches, so scrutinize that code if you find a problem.
• Performance Optimization: If you check to see if there are multiple scripts installed in the system with scriptsInstalled := GetEnvirons(smEnabled), then you can still use your optimized high-speed Roman specific routines when scriptsInstalled <= 1 {Roman is the only script}. Otherwise, users would much prefer that you process their text accurately, than fast and wrong. Most applications would find it best to always use the Script Manager routines which are reasonably fast and very flexible. There are a few high end applications that might find it necessary to use custom routines that do even more than the Script Manager routines offer. However these are generally the exception.
• Font Lists: Some font menus and scrolling lists in dialogs use the application script’s system font to display all font names. This can be a problem when font names are written in their native language. The solution is to use AddResMenu(), which sets a flag so the standard mdef displays each font name with the appropriate script’s system font. Custom mdefs that use the actual font to display its own name also works. Some custom mdefs that normally work will have display problems when the Langauge Kit is installed. You should check yours for side effects.
• Two-Byte Characters: If an application has a font menu, then eventually a user will select a Japanese font. If you use TextEdit, then it should work OK. Otherwise, a common problem is that a character is assumed to be a single byte. You can check for this problem by entering and deleting some Japanese text. Check to see if the insertion point is placed properly and that text wraps appropriately. Backspace to delete characters; each backspace should delete a whole two-byte character, not a single byte. Then test that printing looks the same as on the screen, and that none of the text is lost or formatted incorrectly.
• TextEdit Behavior: TextEdit uses the Script Manager when a non-Roman script is installed. This code will be inabled when the Japanese Language Kit is installled on a US System, and this may introduce some side effects. For example a basic difference is that the word select and line wrapping routines use table driven algorithms in the Script Manager rather than similar customized routines. And this may affect Roman text.
• Hard Coded Fonts: There are a few occasions when a hard coded font should be used to restrict a user to a specific character set. Usually, the font should default to the application font or be selected by the user. It is often appropriate to store preferred font names in a localizable resource. Another approach is to always store a script ID with any text so that the encoding of the text will be unambiguous on a multiscript system. This permits an appropriate font to be chosen with the script ID information.
Language Registration
Applications that have the correct region code set in the ‘vers’ resource will launch with the correct script system font used for the user interface elements of the application. The Language Manager translates from the region code to a script ID to determine the correct font to use for the application.
Concurrent multiple applications can each have their own application script. For compatibility with non-Roman systems, applications with region codes = 0 (US) use the Primary Script (not necessarily the associated Roman script). This allows non-localized applications to continue to use the primary script for its user interface.
Because some applications don’t have the region code set properly, and to give the user more control, there is a Language Register utility that can override the application’s version information. This utility creates a preference file that the Language Manager uses to set the application script. It stores the chooen language and associated script for the named application.
Only applications and desk accessories can be registered with the Language Register. All other system componenets display in the primary script.
Multiple Application Files
If your application is split into multiple files with text resources, then all the creator types will need to match so that the Language Manager can link resource files with the correct application script. For example, if you have an optional balloon help file, the creator needs to be set to the application signature.
Secondary Script Availability
Applications need to be careful when making assumptions about which script systems are installed. In the past, it was common for applications to assume that the primary script plus a secondary Roman script were the only scripts installed. This no longer works since additional secondary scripts are installed with Language Kits. The primary script determines some of the system defaults, and the application script determines the font used in the application’s user interface, but neither indicate all the secondary scripts which are installed.
The only way to confirm which scripts are installed is to poll each script one at a time for all 32 possible scripts to see which are enabled. This information can be used to enable the application’s feature set.
Since the application script only influences the font used to display the user interface, references to other script resources such as date and time formatting should be explicitly referenced to match the font being used to display the data (eg. a Japanese application on an Arabic system will not display dates properly unless the Japanese script’s formats are referenced explicilty).
Font Substitution
Documents that reference uninstalled fonts by name will not have enough information to substitute an appropriate font. It is recommended that both the fontname and FOND ID or Script ID be stored together. This would allow the associated script’s application font to be substituted if the original font is unavailable. Font substitution will be especially common with the Japanese Language Kit, because only a few of the KanjiTalk 7 fonts are bundled. (Even KanjiTalk 7 users will hesitate to install all 40 megabytes of bundled Kanji TrueType fonts.)
Text Services Manager
The Text Services Manager (see references) was introduced in System 7.1 to add support for inline input of two-byte characters (eg. Japanese). This manager is intended for text intensive applications such as word processors and their associated services.
There is an additional extension, Text Services Manager - TextEdit (TSMTE), bundled only with KanjiTalk 7, and not included with the Japanese Language Kit, that extends TextEdit to be compatible with the Text Services Manager. This is an easy way to add inline input support for dialogs and applications that use TextEdit. TSMTE will be incorporated into a future release of System Software.
Multilingual applications
Some applications have multiple sets of resources that specify different localizations of the application. To determine the default localization for your application you can call ApplicationScript := Font2Script(SysFont), and this will give you the font being used by the Language Manager to display the application’s user interrface.
Even though the user chooses from a list of installed languages in the Language Register, only the preferred script (via the SysFont) is available for use. There is no API for the application to get the preferred language information or to set it’s own preferrences. Many scripts support only one language per script, but Roman can support many languages, so a reasonable default would be to choose the application script’s preferred language with PrefLanguage := GetScript(ApplicationScript, smScriptLang). Also, System 7 introduced a new resource used by the Script Manager to map scripts/language/regions. There is currently no external API to convert between script, language and regions, so applications will have to access the ‘itlm’ resource directly to do their own mapping from script to language.
MultiScript Text
A limitation of the Toolbox that will NOT be fixed in this release, is that all system level text is restricted to a single script system . (NOTE: all script systems include the ASCII character set and can display simple English text.) If your application script is Roman, then your dialogs, standard menus, window titles etc. will not be able to display Japanese text because the system uses Chicago to display the text. It is possible for a developer to write custom mdefs, wdefs, cdefs, etc. that are smarter, but the toolbox cannot deal with multiscript text.
What else do I need to know?
This product was designed to be highly compatible with existing applications. There are many places where the behavior of the system was altered to support multiple scripts. All of the following comments are beyond the control of your application, but will affect the user interface.
Views Control Panel
The Macintosh’s file system always uses the primary script to sort and search for file names. In order to support Japanese file names, the Views control panel can be used to select a secondary script font to display the icon names in the Finder. This setting also determines the Finder’s window title font so that Japanese folder/volume names display properly.
These file names can be edited from the Finder, but the Views font must be set to a font for the desired script. The font/script information is not recorded in the file header, so when the views font is changed to another font/script, all filenames are changed to display with the new font/script.
Standard File
In order to be consistent with the Finder, all the standard file dialogs use the font set by the Views control panel to display filenames. Japanese names can also be entered from the standard file dialog, but only if the views font is set to a Japanese font.
The Language Manager substitutes Japanese resources in the standard file open and save dialogs if the application script is Japanese. This allows for the controls to be displayed properly even when the application modifies them at runtime.
Print Drivers
The Language Manager coordinates font changes when primary script drivers are used with secondary script applications that add controls to the printer dialogs. This allows English drivers to be compatible with Japanese applications.
Balloon Help
The Language Manager helps the Help Manager use the correct font when displaying balloon help. It is necessary for the help files to have creator types that associate them with their application. The text in an application’s Finder icon balloon may not display properly if it is not in the primary script.
Unresolved Issues
The Notification Manager always uses the primary script to display it’s messages. This means that messages from secondary script applications may not display properly.
The Application Menu always uses the primary script, so application names that don’t use the primary script may not display correctly.
What should I test?
Here are some potential problem areas where you should pay special attention:
• System dialogs that are modified by the application
• Menus, dialogs, window titles, etc, that display filenames, font names and multiscript text.
• Code that checks for KanjiTalk or multiple scripts.
• Keyboard/font synchronization
• Multiscript text documents
• Non-Roman Systems/Non-Roman applications
• Bilingual applications
• Correct language registration
• Font substitution for missing fonts.
• Balloon Help
• All Script Manager and International Utility calls - dates/time//currency/parsing/sorting/etc.
Glossary
• WorldScript: Apple’s technology that supports multiple script systems. WorldScript is part of the base System 7.1, but only included as necessary for each localized System. There are 2 different extensions, WorldScript I for contextual and bidirectional one-byte scripts, and WorldScript II for two-byte scripts and the Text Services Manager. The Roman script and other simple script systems don’t require either extension.
• Script System: A collection of resources that provides for Apple’s representation of a particular writing system.
• Primary Script: The System’s main script system as determined by the ‘itlc’ resource. The primary script determines the default fonts, sorting and date/time/currency/number formatting used by the System.
• Secondary Script: Is an auxiliary script system which supplies support for additional languages. Multiple secondary scripts are now supported by the Language Manager.
• Application Script: The preferred script for each application’s user interface. The initial default is the appropriate script for the region code in the application’s ‘vers’ resource. If the version’s region code is 0 (US), then the application script always defaults to the primary script. The use can set the preferred script with the Language Register utility.
• Language Manager: A collection of routines used by the system to support secondary scripts. There is currently no public API for the Language Manager.
• System Font/Application Font: Each script system defines an appropriate system font and application forn in its ‘itlb’ resource. The reserved FOND IDs, 0 and 1, map to these, and their respective fonts will change at any time depending on the active script system.
• WorldScript Savvy: A product which is completely WorldScript compatible: can edit and display all one-byte and two-byte characters, including contextual forms.
